home *** CD-ROM | disk | FTP | other *** search
/ Info-Mac 4 / Info_Mac IV CD-ROM (Pacific HiTech Inc.)(August 1994).iso / Development / General / HoW Developer’s Kit 1.1 / HoWLib.h < prev    next >
Text File  |  1994-03-31  |  10KB  |  226 lines
  1. /*______________________________________________________________________
  2.  
  3.     Help on Wheels
  4.     
  5.     Version 1.1
  6.  
  7.     an AWOL Software Production
  8.     PO Box 24207
  9.     300 Eagleson Road
  10.     Kanata, Ontario, Canada K2M 2C3
  11.  
  12.     Internet: ab026@freenet.carleton.ca
  13.     
  14.     Copyright © 1994 Ross Brown.  All rights reserved.
  15.     Portions written by John Norstad are Copyright © 1988, 1989, 1990
  16.     Northwestern University.
  17. _____________________________________________________________________*/
  18.  
  19.  
  20. /*______________________________________________________________________
  21.     
  22.     IMPORTANT:  Applications built using the HoWLib library must
  23.     include a copyright notice containing the following text:
  24.     
  25.     Help interface portion Copyright © 1994 Ross Brown.
  26. _____________________________________________________________________*/
  27.  
  28.  
  29. /*______________________________________________________________________
  30.     
  31.     HoWLib.h - Help on Wheels Library Interface.
  32.  
  33.     This is the interface which supports clients of the Help on Wheels
  34.     help server.  Prospective clients must have the acceptHighLevelEvents
  35.     bit set in their 'SIZE' resource, and must call AEProcessAppleEvent
  36.     from their event loop when they receive an Apple event.  The rest,
  37.     as they say, is magic.
  38.     
  39.     It is desirable, but not required, that clients have the canBackground
  40.     bit set in their 'SIZE' resource.  A client which does not receive
  41.     events while in the background will not be able to respond to the
  42.     canvassing of all processes which the server does at startup, so its
  43.     name will not appear in the server's Help menu until it is brought
  44.     to the foreground, unless that client started the server.  Clients
  45.     supporting Help events do not need to receive events while in the
  46.     background, unless they are background-only, because the server will
  47.     bring the client to the foreground before sending the Help event.
  48.     
  49.     The code segment containing these functions may be relocated or
  50.     purged without concern for safety, except while executing a Help
  51.     event handler.  You may want to call UnloadSeg after each call to
  52.     one of these interface functions.  If you want the segment to
  53.     remain purgeable at all times, you must also call UnloadSeg after
  54.     calling AEProcessAppleEvent, since the segment implements some
  55.     Apple event handlers which it installs at registration time.
  56.     
  57.     See HoWSample's help file for complete information on the use of
  58.     this interface.
  59. _____________________________________________________________________*/
  60.  
  61.  
  62. #ifndef __HOWLIB__
  63. #define __HOWLIB__
  64.  
  65.  
  66. #ifndef __TYPES__
  67. #include <Types.h>
  68. #endif
  69.  
  70. #ifndef __FILES__
  71. #include <Files.h>
  72. #endif
  73.  
  74.  
  75. /* Error codes which clients may receive from this interface: */
  76.  
  77. /* Client (process) does not exist (severe error). */
  78. #define noSuchClientErr                    (-20000)
  79. /* Client (process) exists, but is not registered with server. */
  80. #define clientNotRegisteredErr        (-20001)
  81. /* Apple event support is missing from System. */
  82. #define noAppleEventsErr                (-20002)
  83. /* Process Manager or launch/return support is missing from System. */
  84. #define noProcessMgrErr                    (-20003)
  85. /* Alias Manager support is missing from System. */
  86. #define noAliasMgrErr                    (-20004)
  87. /* FSSpec calls are missing from System. */
  88. #define noFSSpecCallsErr                (-20005)
  89. /* Client is not high-level-event-aware. */
  90. #define notHLEAwareErr                    (-20006)
  91. /* Help file has no master resource. */
  92. #define noMasterResErr                    (-20007)
  93. /* Help server application not found on any volume. */
  94. #define noServerApplErr                    (-20008)
  95. /* Help file version not as specified. */
  96. #define wrongVersionErr                    (-20009)
  97. /* Notification Manager support is missing from System. */
  98. #define noNotificationMgrErr            (-20010)
  99. /* Folder Manager support is missing from System. */
  100. #define noFolderMgrErr                    (-20011)
  101. /* Enhanced Standard File support is missing from System. */
  102. #define noEnhancedStandardFileErr    (-20012)
  103.  
  104.  
  105. /* Operating system creator, file, and resource types: */
  106.  
  107. /* Creator and type of a detached help file.  Help data may be in a */
  108. /* detached help file, or any file, including the main application file. */
  109. /* If the help file is detached, it can be opened or printed by itself. */
  110. #define kHoWHelpCreatorType 'HoW?'
  111. #define kHoWHelpFileType 'HoW!'
  112.  
  113. /* Type of the resource which must be present in the help file to point */
  114. /* to the help data.  The server looks for a resource with the following */
  115. /* IDs, in order: */
  116. /* 1.  the current script's current language code; */
  117. /* 2.  the language code of the server's local version; */
  118. /* 3.  the default language code indicated by the client at registration; */
  119. /* 4.  langEnglish (0). */
  120. /* See HoWRez.{language}.r for comments about resource requirements. */
  121. #define kHoWMasterResType 'HoW!'
  122.  
  123.  
  124. /* Type definitions: */
  125.  
  126. /* Structure type definition of the master resource. */
  127. typedef struct HoWMasterResource {
  128.     short        firstDocID;    /* first doc 'STR#' resource ID */
  129.     short        tconID;        /* 'TCON' resource ID */
  130.     short        tagID;        /* 'TAG ' resource ID */
  131.     short        cellID;        /* 'CELL' resource ID */
  132.     short        alertID;        /* 'ALRT'/'DITL'/'STR ' resource ID */
  133. } HoWMasterResource;
  134.  
  135. /* The Help event handler receives an event id which is the negative */
  136. /* of the tag associated with the clicked text. */
  137. typedef pascal void (*HoWHandlerProcPtr) (short id);
  138.  
  139.  
  140. /* Function prototypes: */
  141.  
  142. #ifdef __cplusplus
  143. extern "C" {
  144. #endif
  145.  
  146. /* Find the help file referenced by the 'alis' resource with ID */
  147. /* "aliasResID" in the resource file with ID "preferencesFileRefNum", */
  148. /* or in the resource file with ID "applicationFileRefNum" if the */
  149. /* resource does not exist in the preferences file or cannot be resolved. */
  150. /* The alias record, possibly changed by UpdateAlias, is written back to */
  151. /* the preferences file if possible.  The application file is not changed. */
  152. /* Resolution is relative to the application file, so it can take */
  153. /* advantage of relative information in the alias resource if present. */
  154. /* If the help file cannot be found by a fast search, one exhaustive */
  155. /* search will be done on the alias record in the application file. */
  156. /* A failed exhaustive search is noted in the preferences file so that it */
  157. /* is not repeated; this note remains until the preferences file is */
  158. /* deleted, or until a later fast search successfully finds the help file. */
  159. /* If you do not maintain a separate preferences file, set both resource */
  160. /* file IDs to the same value, and the application file will be treated */
  161. /* as though it were also the preferences file. */
  162. pascal OSErr HoWFindHelpFile (short preferencesFileRefNum,
  163.                               short applicationFileRefNum,
  164.                               short aliasResID, FSSpecPtr helpFile);
  165.  
  166. /* Register or re-register with the help server.  The help file may */
  167. /* be any file, including the main application file.  If the help file */
  168. /* has a 'vers'(1) resource, and the version (first word) does not match */
  169. /* "version", wrongVersionErr is returned.  If there is no master resource */
  170. /* in the help file for the current script's current language, nor for */
  171. /* "defaultLanguage", nor for langEnglish, noMasterResErr is returned. */
  172. /* The server will prefer to use its own language over "defaultLanguage". */
  173. /* By re-registering, the client can switch to another help file.  If the */
  174. /* server is not already started, and "startServer" is true, HoWRegister */
  175. /* will try to start the server, which may result in many OS error codes, */
  176. /* as well as noServerApplErr, a non-fatal code returned for your */
  177. /* information (see HoWDisplay below).  If the server is not already */
  178. /* started, and "startServer" is false (which it should be for most */
  179. /* clients), the usual return code is noErr, meaning that the actual */
  180. /* registration has been deferred until the first non-casual display */
  181. /* (see below) or until the server starts by some other method.  Gestalt */
  182. /* checks may result in other error codes listed above; the expected */
  183. /* error code under System 6 is noAppleEventsErr.  The Help event */
  184. /* handler is optional; pass nil if the client does not support them. */
  185. pascal OSErr HoWRegister (const FSSpec *helpFile, short version,
  186.                           LangCode defaultLanguage, Boolean startServer,
  187.                           HoWHandlerProcPtr handler);
  188.  
  189. /* Display the help file at the indicated tag position.  If "tag" */
  190. /* is zero, the last seen position is retained.  If the server */
  191. /* is not already started, and "casual" is false, this will attempt */
  192. /* to start the server; if the server is absent, the user sees an */
  193. /* alert offering to save a readable copy using TeachText and open */
  194. /* it for viewing, unless the client is background-only, in which case */
  195. /* no alerts appear, and the document is created on the desktop. */
  196. /* A casual display is effective only if the server is started and */
  197. /* running in the background, with the "follow" option in effect, */
  198. /* and already displaying this client's help file.  A casual display */
  199. /* always leaves the client in the foreground; a non-casual display */
  200. /* always brings the server to the foreground.  Note that modal dialogs */
  201. /* will prevent the server from coming to the foreground unless they */
  202. /* are hidden before this call. */
  203. pascal OSErr HoWDisplay (short tag, Boolean casual);
  204.  
  205. /* Deregister with the help server.  If the client fails to deregister */
  206. /* before it exits, the server will deregister it automatically. */
  207. pascal OSErr HoWDeregister (void);
  208.  
  209. /* Launch the help server, if necessary, to open and display the given */
  210. /* help file.  This method is suggested for use by programs which are not */
  211. /* applications; applications should use HoWRegister instead (see above). */
  212. /* If the server is absent, a TeachText copy is created on the desktop */
  213. /* and opened (as for a background-only application calling HoWDisplay). */
  214. /* Version checking is not performed, and the current script's current */
  215. /* language is always used.  This may be called by 'INIT' logic in control */
  216. /* panels or extensions, because it uses the Notification Manager; allow */
  217. /* 5000 bytes when calculating the system heap requirement for your */
  218. /* 'sysz' resource. */
  219. pascal OSErr HoWOpen (const FSSpec *helpFile);
  220.  
  221. #ifdef __cplusplus
  222. }
  223. #endif
  224.  
  225.  
  226. #endif